<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
<HTML>
<HEAD>
<TITLE>JpGraph Manual (ver:30 Oct 2002 09:48)</TITLE>
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; CHARSET=iso-8859-1">
<STYLE TYPE="text/css"><!--
BODY { font-family: serif }
H1 { font-family: sans-serif }
H2 { font-family: sans-serif }
H3 { font-family: sans-serif }
H4 { font-family: sans-serif }
H5 { font-family: sans-serif }
H6 { font-family: sans-serif }
SUB { font-size: smaller }
SUP { font-size: smaller }
PRE { font-family: monospace }
A { text-decoration: none }
--></STYLE>
</HEAD>
<BODY>
<IMG  src="img/JpGraph_Logo.png">
<A HREF="index.html">Contents</A>
<A HREF="22working.html">Previous</A>
<A HREF="2220fonts.html">Next</A>
<HR>
<H2><A NAME="4_2">4.2 How to generate images with PHP</A></H2>
 As a general rule each PHP script which generates an image must be
 specified in a separate file which is then called in an &lt;IMG&gt; tag
 reference. For example, the following HTML excerpt includes the image
 generated by the PHP script in &quot;fig1.php&quot;.
<P>
<BR> &nbsp;
<BR><DIV style="background-color:#E6E6E6;font-family:courier new;font-size:85%;font-weight:bold;">
<B><CODE><FONT color="#000000"><FONT color="#0000CC"></FONT><FONT color="#006600">
 &lt;</FONT><FONT color="#0000CC">img&nbsp;src</FONT><FONT color="#006600">=</FONT><FONT
color="#CC0000">&quot;fig1.php&quot;&nbsp;</FONT><FONT color="#0000CC">border</FONT><FONT
color="#006600">=</FONT><FONT color="#0000CC">0&nbsp;align</FONT><FONT color="#006600">
=</FONT><FONT color="#0000CC">center&nbsp;width</FONT><FONT color="#006600">=</FONT><FONT
color="#0000CC">300&nbsp;height</FONT><FONT color="#006600">=</FONT><FONT color="#0000CC">
200</FONT><FONT color="#006600">&gt;</FONT><FONT color="#0000CC"></FONT></FONT>
</CODE></B></DIV></P>
<P></P>
<P> The library will automatically generate the necessary headers to be
 sent back to the browser to correctly recognize the data stream as an
 image of either PNG/GIF/JPEG format. The browser can then correctly
 decode the image</P>
<P> Observere that you<STRONG> can't</STRONG> return anything else than
 an image from the image script. By definition each HTML page can only
 consist of one mime type which is determined by the sent headers.</P>
<P> A common mistake is to have a space in the beginning of the image
 script file which the HTTP server will send back to the browser. The
 browser now assumes that the data comming back from this script is
 normal ASCII. When then the image headers get send back to the browser
 to forwarn the browser of the forthcomming image the browser will not
 like that. It has already determined that the script should only send
 ASCII data back and will then give you a &quot;Headers already sent error&quot;.</P>
<P> To include several images together with text on a page you need to
 have a parent page with several &lt;IMG&gt; which each refers to an image
 script.</P>
<P> To get access to the library you will need to include at least two
 files, the base library and one or more of the plot extensions. So for
 example if you want to do line plots the top of your PHP file must have
 the lines:
<BR> &nbsp;
<BR><DIV style="background-color:#E6E6E6;font-family:courier new;font-size:85%;font-weight:bold;">
<B><CODE><FONT color="#000000"><FONT color="#0000CC"></FONT><FONT color="#006600">
 &lt;?</FONT><FONT color="#0000CC">php
<BR />
<BR /></FONT><FONT color="#006600">include&nbsp;(</FONT><FONT color="#CC0000">
'jpgraph.php'</FONT><FONT color="#006600">);
<BR />include&nbsp;(</FONT><FONT color="#CC0000">'jpgraph_line.php'</FONT><FONT
color="#006600">);
<BR />...
<BR />&nbsp;</FONT><FONT color="#FF9900">// Code that uses the jpgraph
 library
<BR /></FONT><FONT color="#006600">...
<BR /></FONT><FONT color="#0000CC"></FONT></FONT></CODE></B></DIV></P>
<P></P>
<P></P>
<HR> <SMALL><STRONG> Sidebar:</STRONG> You might also use the PHP
 directive requires(). The difference is subtle in that include will
 only include the code if the include statement is actually excuted.
 While require() will always be replaced by the file specified. See PHP
 documentation for further explanation. For most practical purposes they
 are identical.</SMALL>
<HR>
<H2><A NAME="4_3">4.3 The basic principle of JpGraph and the creation of
 images</A></H2>
 You will see that the common pattern for creating graphs is to
<OL>
<LI> Create a script that constructs the image, type, colors size and so
 on.</LI>
<LI> A wrapper script which contains one or more &lt;IMG&gt; tags to position
 the graphs on the proper HTML page.</LI>
</OL>
 Of course it is of perfectly possible to call the image script directly
 in the browser to just display the generated image in the browser.
<P> You shopuld remember that it is also possible to pass arguments to
 the image script via the normal HTTP parameters, for example
<BR> &nbsp;
<BR><DIV style="background-color:#E6E6E6;font-family:courier new;font-size:85%;font-weight:bold;">
<B><CODE><FONT color="#000000"><FONT color="#0000CC"></FONT><FONT color="#006600">
 &lt;</FONT><FONT color="#0000CC">img&nbsp;src</FONT><FONT color="#006600">=</FONT><FONT
color="#CC0000">&quot;showgraph.php?a=1&amp;b=2&quot;</FONT><FONT color="#006600">&gt;</FONT><FONT
color="#0000CC"></FONT></FONT></CODE></B></DIV></P>
<P> This could for example be used to control the apperance of the image
 or perhaps send data to the image which will be displayed. Note that
 this is probably not the best way to send large amount of data to plot.
 Instead the only practical way, for large data sizes, is to get all the
 data in the image script, perhaps from a DB.</P>
<HR> <SMALL><STRONG> Tips: Forcing the browser to update your image</STRONG>
 Some browser may not send back a request to the web browser unless the
 user presses &quot;Refresh&quot; (F5 - in most browsers). This can lead to
 problems that the user is seeing old data. A simple trick is to add a
 dummy time argument which is not used in the script. For example
<BR> &nbsp;
<BR><DIV style="background-color:#E6E6E6;font-family:courier new;font-size:85%;font-weight:bold;">
<B><CODE><FONT color="#000000"><FONT color="#0000CC"></FONT><FONT color="#006600">
 echo&nbsp;</FONT><FONT color="#CC0000">&quot;&lt;img src='myimagescript.php?dummy=&quot;</FONT><FONT
color="#006600">.</FONT><FONT color="#0000CC">now</FONT><FONT color="#006600">
().</FONT><FONT color="#CC0000">&quot;'&gt;&quot;</FONT><FONT color="#0000CC"></FONT></FONT>
</CODE></B></DIV>
<P></P>
<HR>
<P> When it comes to the structure of your imaging script they will
 generally have the structure
<BR> &nbsp;
<BR><DIV style="background-color:#E6E6E6;font-family:courier new;font-size:85%;font-weight:bold;">
<B><CODE><FONT color="#000000"><FONT color="#0000CC"></FONT><FONT color="#FF9900">
 // ... Include necessary headers
<BR />
<BR /></FONT><FONT color="#0000CC">$graph&nbsp;</FONT><FONT color="#006600">
=&nbsp;new&nbsp;</FONT><FONT color="#0000CC">Graph</FONT><FONT color="#006600">(</FONT><FONT
color="#0000CC">$width</FONT><FONT color="#006600">,</FONT><FONT color="#0000CC">
$height</FONT><FONT color="#006600">,&nbsp;...);
<BR />
<BR /></FONT><FONT color="#FF9900">// ... code to construct the graph
 details
<BR />
<BR /></FONT><FONT color="#0000CC">$graph</FONT><FONT color="#006600">-&gt;</FONT><FONT
color="#0000CC">Stroke</FONT><FONT color="#006600">();
<BR /></FONT><FONT color="#0000CC"></FONT></FONT></CODE></B></DIV></P>
<P> JpGraph is completely Object oriented so all calls will be action on
 specific instances of classes. One of the fundamental classes is the
 Graph() class which represents the entire graph.</P>
<P> After the creation of the Graph() object you add all your lines of
 code to construct the details of the graph.</P>
<P> As the final call you will send the generated image back to the
 browser with a call to the Stroke() method.</P>
<P> <SMALL>Note: This is not always true, but to keep things simple for
 the moment we assume this.</SMALL></P>
<P> In addition to this standard usage pattern you can also send the
 graph directly to a file, get the GD image handler for the image and
 also make use of the builtin cache system. The cache system, which
 lessens the burden of the PHP server, works by avoiding o run all the
 code that follows the initial Graph() call by checking if the image has
 already been created and in that case directly send back the previously
 created (and filed) image to the browser. When using the cache system
 you must specify a filename which is used to store the image in the
 cache system and possibly also a timeout value to indicate how long the
 image in the cache directory should be valid. For this reason you might
 in the following examples, for example, see the code
<BR> &nbsp;
<BR><DIV style="background-color:#E6E6E6;font-family:courier new;font-size:85%;font-weight:bold;">
<B><CODE><FONT color="#000000"><FONT color="#0000CC"> $graph&nbsp;</FONT><FONT
color="#006600">=&nbsp;new&nbsp;</FONT><FONT color="#0000CC">Graph</FONT><FONT color="#006600">
(</FONT><FONT color="#0000CC">300</FONT><FONT color="#006600">,</FONT><FONT
color="#0000CC">200</FONT><FONT color="#006600">,</FONT><FONT color="#CC0000">
&quot;auto&quot;</FONT><FONT color="#006600">);</FONT><FONT color="#0000CC"></FONT>
</FONT></CODE></B></DIV></P>
<P> in the start of all the examples. The two first parameters specify
 the width and height of the graph and the third parameter the name of
 the image file in the cache directory. The special name 'auto'
 indicates that the image file will begiven the same name as the image
 script but with the extension changed to indicate the graphic format
 used, i.e '.jpg', '.png' and so on.</P>
<H2><A NAME="4_4">4.4  Chosing the image format for JpGraph</A></H2>
 By default JpGraph automatically chooses the image format to use in the
 order PNG, JPEG and GIF. The exact format depends on what is available
 on your system. There are two ways you can influence the way the
 graphic format is choosen.
<OL>
<LI> Change the default graphic format by changing the DEFINE
<BR> &nbsp;
<BR><DIV style="background-color:#E6E6E6;font-family:courier new;font-size:85%;font-weight:bold;">
<B><CODE><FONT color="#000000"><FONT color="#0000CC"> DEFINE</FONT><FONT color="#006600">
(</FONT><FONT color="#CC0000">&quot;DEFAULT_GFORMAT&quot;</FONT><FONT color="#006600">
,</FONT><FONT color="#CC0000">&quot;auto&quot;</FONT><FONT color="#006600">);</FONT><FONT
color="#0000CC"></FONT></FONT></CODE></B></DIV></LI>
<P></P>
<LI> Set the graphic format in your script by calling the method<A href="../ref/Image.html#_IMAGE_SETIMGFORMAT">
 SetImgFormat()</A> For example, to force your script to use JPEG in one
 specific image use
<BR> &nbsp;
<BR><DIV style="background-color:#E6E6E6;font-family:courier new;font-size:85%;font-weight:bold;">
<B><CODE><FONT color="#000000"><FONT color="#0000CC"> $graph</FONT><FONT color="#006600">
-&gt;</FONT><FONT color="#0000CC">img</FONT><FONT color="#006600">-&gt;</FONT><FONT
color="#0000CC">SetImgFormat</FONT><FONT color="#006600">(</FONT><FONT color="#CC0000">
&quot;jpeg&quot;</FONT><FONT color="#006600">)</FONT><FONT color="#0000CC"></FONT></FONT>
</CODE></B></DIV></LI>
<P></P>
</OL>
<H2><A NAME="4_5">4.5 Alternatives to streaming back the image</A></H2>
 If you like to save the image directly to a file instead of streaming
 it back to the browser then you just have to specify an absolute
 filename in the final call to Graph::Stroke(), i.e.
<P>
<BR> &nbsp;
<BR><DIV style="background-color:#E6E6E6;font-family:courier new;font-size:85%;font-weight:bold;">
<B><CODE><FONT color="#000000"><FONT color="#0000CC"> $graph</FONT><FONT color="#006600">
-&gt;</FONT><FONT color="#0000CC">Stroke</FONT><FONT color="#006600">(</FONT><FONT
color="#CC0000">&quot;/usr/home/peter/images/result2002.png&quot;</FONT><FONT color="#006600">
);</FONT><FONT color="#0000CC"></FONT></FONT></CODE></B></DIV></P>
<P></P>
<P> Please note that the user running as Apache/PHP must have write
 access to the specified directory.</P>
<P> There are also two predefined filenames which have special meaning.</P>
<UL>
<LI>&quot;auto&quot;, This will create a file in the same directory as the script
 with the same name as the script but with the correct image extension.</LI>
<LI>_IMG_HANDLER, (This is defined in jpgraph.php). Specifying this
 filename will not create a an image to file or stram it back to the
 browser. Instead it will instruct the Stroke() method to just return
 the handle for the GD image. This is usefull if you later want to
 manipulate the image in ways that are not yet supported by Jpgraph. For
 example include the image in generated PDF files.
<BR><I> Example:</I>
<BR> &nbsp;
<BR><DIV style="background-color:#E6E6E6;font-family:courier new;font-size:85%;font-weight:bold;">
<B><CODE><FONT color="#000000"><FONT color="#0000CC"> $handle&nbsp;</FONT><FONT
color="#006600">=&nbsp;</FONT><FONT color="#0000CC">$graph</FONT><FONT color="#006600">
-&gt;</FONT><FONT color="#0000CC">Strokg</FONT><FONT color="#006600">(</FONT><FONT
color="#0000CC">_IMG_HANDLER</FONT><FONT color="#006600">);</FONT><FONT color="#0000CC">
</FONT></FONT></CODE></B></DIV></LI>
<P></P>
</UL>
</SMALL><HR>
<IMG  src="img/JpGraph_Logo.png">
<A HREF="index.html">Contents</A>
<A HREF="22working.html">Previous</A>
<A HREF="2220fonts.html">Next</A>
</BODY>
</HTML>
